home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / p_man / cat3 / diagnostics.Z / diagnostics
Encoding:
Text File  |  1998-10-28  |  7.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))  22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))    ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       diagnostics -    Perl compiler pragma to    force verbose warning
  10.       diagnostics
  11.  
  12.       splain - standalone program to do the    same thing
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.       As a pragma:
  16.  
  17.           use diagnostics;
  18.           use diagnostics -verbose;
  19.  
  20.           enable  diagnostics;
  21.           disable diagnostics;
  22.  
  23.       Aa a program:
  24.  
  25.           perl program 2>diag.out
  26.           splain [-v] [-p] diag.out
  27.  
  28.  
  29.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  30.       TTTThhhheeee ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss Pragma
  31.  
  32.       This module extends the terse    diagnostics normally emitted
  33.       by both the perl compiler and    the perl interpeter,
  34.       augmenting them with the more    explicative and    endearing
  35.       descriptions found in    the _p_e_r_l_d_i_a_g manpage.  Like the    other
  36.       pragmata, it affects the compilation phase of    your program
  37.       rather than merely the execution phase.
  38.  
  39.       To use in your program as a pragma, merely invoke
  40.  
  41.           use diagnostics;
  42.  
  43.       at the start (or near    the start) of your program.  (Note
  44.       that this _d_o_e_s enable    perl's ----wwww flag.)  Your whole
  45.       compilation will then    be _s_u_b_j_e_c_t(ed :-) to the enhanced
  46.       diagnostics.    These still go out SSSSTTTTDDDDEEEERRRRRRRR.
  47.  
  48.       Due to the interaction between runtime and compiletime
  49.       issues, and because it's probably not    a very good idea
  50.       anyway, you may not use no diagnostics to turn them off at
  51.       compiletime.    However, you may control there behaviour at
  52.       runtime using    the _d_i_s_a_b_l_e() and _e_n_a_b_l_e() methods to turn
  53.       them off and on respectively.
  54.  
  55.       The ----vvvveeeerrrrbbbboooosssseeee flag first prints out the the _p_e_r_l_d_i_a_g manpage
  56.       introduction before any other    diagnostics.  The
  57.       $diagnostics::PRETTY variable    can generate nicer escape
  58.       sequences for    pagers.
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))  22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))    ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))
  71.  
  72.  
  73.  
  74.       TTTThhhheeee _s_p_l_a_i_n Program
  75.  
  76.       While    apparently a whole nuther program, _s_p_l_a_i_n is actually
  77.       nothing more than a link to the (executable) _d_i_a_g_n_o_s_t_i_c_s._p_m
  78.       module, as well as a link to the _d_i_a_g_n_o_s_t_i_c_s._p_o_d
  79.       documentation.  The ----vvvv flag is like the use diagnostics
  80.       -verbose directive.  The ----pppp flag is like the
  81.       $diagnostics::PRETTY variable.  Since    you're post-processing
  82.       with _s_p_l_a_i_n, there's no sense    in being able to _e_n_a_b_l_e() or
  83.       _d_i_s_a_b_l_e() processing.
  84.  
  85.       Output from _s_p_l_a_i_n is    directed to SSSSTTTTDDDDOOOOUUUUTTTT, unlike the pragma.
  86.  
  87.      EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  88.       The following    file is    certain    to trigger a few errors    at
  89.       both runtime and compiletime:
  90.  
  91.           use diagnostics;
  92.           print NOWHERE "nothing\n";
  93.           print STDERR "\n\tThis message should be unadorned.\n";
  94.           warn "\tThis is a    user warning";
  95.           print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
  96.           my $a, $b    = scalar <STDIN>;
  97.           print "\n";
  98.           print $x/$y;
  99.  
  100.       If you prefer    to run your program first and look at its
  101.       problem afterwards, do this:
  102.  
  103.           perl -w test.pl 2>test.out
  104.           ./splain < test.out
  105.  
  106.       Note that this is not    in general possible in shells of more
  107.       dubious heritage, as the theoretical
  108.  
  109.           (perl -w test.pl >/dev/tty) >& test.out
  110.           ./splain < test.out
  111.  
  112.       Because you just moved the existing ssssttttddddoooouuuutttt to    somewhere
  113.       else.
  114.  
  115.       If you don't want to modify your source code,    but still have
  116.       on-the-fly warnings, do this:
  117.  
  118.           exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&-    | splain 1>&2 3>&-
  119.  
  120.       Nifty, eh?
  121.  
  122.       If you want to control warnings on the fly, do something
  123.       like this.  Make sure    you do the use first, or you won't be
  124.       able to get at the _e_n_a_b_l_e() or _d_i_s_a_b_l_e() methods.
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))  22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))    ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))
  137.  
  138.  
  139.  
  140.           use diagnostics; # checks    entire compilation phase
  141.           print    "\ntime    for 1st    bogus diags: SQUAWKINGS\n";
  142.           print    BOGUS1 'nada';
  143.           print    "done with 1st bogus\n";
  144.  
  145.           disable diagnostics; # only turns    off runtime warnings
  146.           print    "\ntime    for 2nd    bogus: (squelched)\n";
  147.           print    BOGUS2 'nada';
  148.           print    "done with 2nd bogus\n";
  149.  
  150.           enable diagnostics; # turns back on runtime warnings
  151.           print    "\ntime    for 3rd    bogus: SQUAWKINGS\n";
  152.           print    BOGUS3 'nada';
  153.           print    "done with 3rd bogus\n";
  154.  
  155.           disable diagnostics;
  156.           print    "\ntime    for 4th    bogus: (squelched)\n";
  157.           print    BOGUS4 'nada';
  158.           print    "done with 4th bogus\n";
  159.  
  160.  
  161.      IIIINNNNTTTTEEEERRRRNNNNAAAALLLLSSSS
  162.       Diagnostic messages derive from the _p_e_r_l_d_i_a_g._p_o_d file    when
  163.       available at runtime.     Otherwise, they may be    embedded in
  164.       the file itself when the splain package is built.   See the
  165.       _M_a_k_e_f_i_l_e for details.
  166.  
  167.       If an    extant $SIG{__WARN__} handler is discovered, it    will
  168.       continue to be honored, but only after the
  169.       _d_i_a_g_n_o_s_t_i_c_s::_s_p_l_a_i_n_t_h_i_s() function (the module's
  170.       $SIG{__WARN__} interceptor) has had its way with your
  171.       warnings.
  172.  
  173.       There    is a $diagnostics::DEBUG variable you may set if
  174.       you're desperately curious what sorts    of things are being
  175.       intercepted.
  176.  
  177.           BEGIN { $diagnostics::DEBUG = 1 }
  178.  
  179.  
  180.      BBBBUUUUGGGGSSSS
  181.       Not being able to say    "no diagnostics" is annoying, but may
  182.       not be insurmountable.
  183.  
  184.       The -pretty directive    is called too late to affect matters.
  185.       You have to do this instead, and _b_e_f_o_r_e you load the module.
  186.  
  187.           BEGIN { $diagnostics::PRETTY = 1 }
  188.  
  189.       I could start    up faster by delaying compilation until    it
  190.       should be needed, but    this gets a "panic: top_level" when
  191.       using    the pragma form    in Perl    5.001e.
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))  22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))    ddddiiiiaaaaggggnnnnoooossssttttiiiiccccssss((((3333))))
  203.  
  204.  
  205.  
  206.       While    it's true that this documentation is somewhat
  207.       subserious, if you use a program named _s_p_l_a_i_n, you should
  208.       expect a bit of whimsy.
  209.  
  210.      AAAAUUUUTTTTHHHHOOOORRRR
  211.       Tom Christiansen <_t_c_h_r_i_s_t@_m_o_x._p_e_r_l._c_o_m>, 25 June 1995.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                        (printed 10/23/98)
  262.  
  263.  
  264.  
  265.